Usenet 1993 July/InfoMagic USENET CD-ROM July 1993.ISO/sources/misc/volume25/tcl/part32

Text File | 1991-11-15 | 43.6 KB | 1,026 lines

Newsgroups: comp.sources.misc
From: [e-mail] (Karl Lehenbauer)
Subject:  v25i100:  tcl - tool command language, version 6.1, Part32/33
Message-ID: <[e-mail]>
X-Md4-Signature: 73264eab3c3709eaf41f45e569626c29
Date: Fri, 15 Nov 1991 23:01:32 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Karl Lehenbauer)
Posting-number: Volume 25, Issue 100
Archive-name: tcl/part32
Environment: UNIX

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of archive 32 (of 33)."
# Contents:  tcl6.1/doc/Tcl.man.3
# Wrapped by karl@one on Tue Nov 12 19:44:33 1991
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'tcl6.1/doc/Tcl.man.3' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'tcl6.1/doc/Tcl.man.3'\"
else
echo shar: Extracting \"'tcl6.1/doc/Tcl.man.3'\" \(41512 characters\)
sed "s/^X//" >'tcl6.1/doc/Tcl.man.3' <<'END_OF_FILE'
X.TP
X\fBinfo vars\fR ?\fIpattern\fR?
XIf \fIpattern\fR isn't specified,
Xreturns a list of all the names of currently-visible variables, including
Xboth locals and currently-visible globals.
XIf \fIpattern\fR is specified, only those names matching \fIpattern\fR
Xare returned.  Matching is determined using the same rules as for
X\fBstring match\fR.
X.RE
X.TP
X\fBjoin \fIlist \fR?\fIjoinString\fR?
X.VS
XThe \fIlist\fR argument must be a valid Tcl list.
XThis command returns the string
Xformed by joining all of the elements of \fIlist\fR together with
X\fIjoinString\fR separating each adjacent pair of elements.
XThe \fIjoinString\fR argument defaults to a space character.
X.VE
X.TP
X\fBlappend \fIvarName value \fR?\fIvalue value ...\fR?
X.VS
XTreat the variable given by \fIvarName\fR as a list and append
Xeach of the \fIvalue\fR arguments to that list as a separate
Xelement, with spaces between elements.
XIf \fIvarName\fR doesn't exist, it is created as a list with elements
Xgiven by the \fIvalue\fR arguments.
X\fBLappend\fR is similar to \fBappend\fR except that the \fIvalue\fRs
Xare appended as list elements rather than raw text.
XThis command provides a relatively efficient way to build up
Xlarge lists.  For example, ``\fBlappend a $b\fR'' is much
Xmore efficient than ``\fBset a [concat $a [list $b]]\fR'' when
X\fB$a\fR is long.
X.TP
X\fBlindex \fIlist index\fR
XTreats \fIlist\fR as a Tcl list and returns the \fIindex\fR'th element
Xfrom it (0 refers to the first element of the list).
XIn extracting the element, \fIlindex\fR observes the same rules
Xconcerning braces and quotes and backslashes as the Tcl command
Xinterpreter; however, variable
Xsubstitution and command substitution do not occur.
XIf \fIindex\fR is negative or greater than or equal to the number
Xof elements in \fIvalue\fR, then an empty
Xstring is returned.
X.TP
X\fBlinsert \fIlist index element \fR?\fIelement element ...\fR?
XThis command produces a new list from \fIlist\fR by inserting all
Xof the \fIelement\fR arguments just before the \fIindex\fRth
Xelement of \fIlist\fR.  Each \fIelement\fR argument will become
Xa separate element of the new list.  If \fIindex\fR is less than
Xor equal to zero, then the new elements are inserted at the
Xbeginning of the list.  If \fIindex\fR is greater than or equal
Xto the number of elements in the list, then the new elements are
Xappended to the list.
X.VE
X.TP
X\fBlist \fIarg \fR?\fIarg ...\fR?
XThis command returns a list comprised of all the \fIarg\fRs.  Braces
Xand backslashes get added as necessary, so that the \fBindex\fR command
Xmay be used on the result to re-extract the original arguments, and also
Xso that \fBeval\fR may be used to execute the resulting list, with
X\fIarg1\fR comprising the command's name and the other \fIarg\fRs comprising
Xits arguments.  \fBList\fR produces slightly different results than
X\fBconcat\fR:  \fBconcat\fR removes one level of grouping before forming
Xthe list, while \fBlist\fR works directly from the original arguments.
XFor example, the command
X.RS
X.DS
X\fBlist a b {c d e} {f {g h}}
X.DE
Xwill return
X.DS
X\fBa b {c d e} {f {g h}}
X.DE
Xwhile \fBconcat\fR with the same arguments will return
X.DS
X\fBa b c d e f {g h}\fR
X.DE
X.RE
X.br
X.VS
X.TP
X\fBllength \fIlist\fR
XTreats \fIlist\fR as a list and returns a decimal string giving
Xthe number of elements in it.
X.TP
X\fBlrange \fIlist first last
X\fIList\fR must be a valid Tcl list.  This command will
Xreturn a new list consisting of elements
X\fIfirst\fR through \fIlast\fR, inclusive.
X\fILast\fR may be \fBend\fR (or any
Xabbreviation of it) to refer to the last element of the list.
XIf \fIfirst\fR is less than zero, it is treated as if it were zero.
XIf \fIlast\fR is greater than or equal to the number of elements
Xin the list, then it is treated as if it were \fBend\fR.
XIf \fIfirst\fR is greater than \fIlast\fR then an empty string
Xis returned.
XNote: ``\fBlrange \fIlist first first\fR'' does not always produce the
Xsame result as ``\fBlindex \fIlist first\fR'' (although it often does
Xfor simple fields that aren't enclosed in braces); it does, however,
Xproduce exactly the same results as ``\fBlist [lindex \fIlist first\fB]\fR''
X.TP
X\fBlreplace \fIlist first last \fR?\fIelement element ...\fR?
XReturns a new list formed by replacing one or more elements of
X\fIlist\fR with the \fIelement\fR arguments.
X\fIFirst\fR gives the index in \fIlist\fR of the first element
Xto be replaced.
XIf \fIfirst\fR is less than zero then it refers to the first
Xelement of \fIlist\fR;  the element indicated by \fIfirst\fR
Xmust exist in the list.
X\fILast\fR gives the index in \fIlist\fR of the last element
Xto be replaced;  it must be greater than or equal to \fIfirst\fR.
X\fILast\fR may be \fBend\fR (or any abbreviation of it) to indicate
Xthat all elements between \fIfirst\fR and the end of the list should
Xbe replaced.
XThe \fIelement\fR arguments specify zero or more new arguments to
Xbe added to the list in place of those that were deleted.
XEach \fIelement\fR argument will become a separate element of
Xthe list.
XIf no \fIelement\fR arguments are specified, then the elements
Xbetween \fIfirst\fR and \fIlast\fR are simply deleted.
X.TP
X\fBlsearch \fIlist pattern\fR
XSearch the elements of \fIlist\fR to see if one of them matches
X\fIpattern\fR.
XIf so, the command returns the index of the first matching
Xelement.
XIf not, the command returns \fB\-1\fR.
XPattern matching is done in the same way as for the \fBstring match\fR
Xcommand.
X.TP
X\fBlsort \fIlist\fR
XSort the elements of \fIlist\fR, returning a new list in sorted
Xorder.
XASCII sorting is used, with the result in increasing order.
X.VE
X.TP
X\fBopen \fIfileName\fR ?\fIaccess\fR?
X.VS
XOpens a file and returns an identifier
Xthat may be used in future invocations
Xof commands like \fBread\fR, \fBwrite\fR, and \fBclose\fR.
X\fIFileName\fR gives the name of the file to open; if it starts with
Xa tilde then tilde substitution is performed as described for
X\fBTcl_TildeSubst\fR.
XIf the first character of \fIfileName\fR is ``|'' then the
Xremaining characters of \fIfileName\fR are treated as a command
Xpipeline to invoke, in the same style as for \fBexec\fR.
XIn this case, the identifier returned by \fBopen\fR may be used
Xto write to the command's input pipe or read from its output pipe.
XThe \fIaccess\fR argument indicates the way in which the file
X(or command pipeline) is to be accessed.
XIt may have any of the following values:
X.RS
X.TP
X\fBr\fR
XOpen the file for reading only; the file must already exist.
X.TP
X\fBr+\fR
XOpen the file for both reading and writing; the file must
Xalready exist.
X.TP
X\fBw\fR
XOpen the file for writing only.  Truncate it if it exists.  If it doesn't
Xexist, create a new file.
X.TP
X\fBw+\fR
XOpen the file for reading and writing.  Truncate it if it exists.
XIf it doesn't exist, create a new file.
X.TP
X\fBa\fR
XOpen the file for writing only.  The file must already exist, and the file
Xis positioned so that new data is appended to the file.
X.TP
X\fBa+\fR
XOpen the file for reading and writing.  The file must already exist, and
Xthe initial access position is set to the end of the file.
X.PP
X\fIAccess\fR defaults to \fBr\fR.
XIf a file is opened for both reading and writing, then \fBseek\fR
Xmust be invoked between a read and a write, or vice versa (this
Xrestriction does not apply to command pipelines opened with \fBopen\fR).
XWhen \fIfileName\fR specifies a command pipeline and a write-only access
Xis used, then standard output from the pipeline is directed to the
Xcurrent standard output unless overridden by the command.
XWhen \fIfileName\fR specifies a command pipeline and a read-only access
Xis used, then standard input from the pipeline is taken from the
Xcurrent standard input unless overridden by the command.
X.RE
X.VE
X.TP
X\fBproc \fIname args body\fR
XThe \fBproc\fR command creates a new Tcl command procedure,
X\fIname\fR, replacing
Xany existing command there may have been by that name.  Whenever the
Xnew command is invoked, the contents of \fIbody\fR will be executed
Xby the Tcl interpreter.  \fIArgs\fR specifies the formal arguments to the
Xprocedure.  It consists of a list, possibly empty, each of whose
Xelements specifies
Xone argument.  Each argument specifier is also a list with either
Xone or two fields.  If there is only a single field in the specifier,
Xthen it is the name of the argument; if there are two fields, then
Xthe first is the argument name and the second is its default value.
Xbraces and backslashes may be used in the usual way to specify
Xcomplex default values.
X.IP
XWhen \fIname\fR is invoked, a local variable
Xwill be created for each of the formal arguments to the procedure; its
Xvalue will be the value of corresponding argument in the invoking command
Xor the argument's default value.
XArguments with default values need not be
Xspecified in a procedure invocation.  However, there must be enough
Xactual arguments for all the
Xformal arguments that don't have defaults, and there must not be any extra
Xactual arguments.  There is one special case to permit procedures with
Xvariable numbers of arguments.  If the last formal argument has the name
X\fBargs\fR, then a call to the procedure may contain more actual arguments
Xthan the procedure has formals.  In this case, all of the actual arguments
Xstarting at the one that would be assigned to \fBargs\fR are combined into
Xa list (as if the \fBlist\fR command had been used); this combined value
Xis assigned to the local variable \fBargs\fR.
X.IP
XWhen \fIbody\fR is being executed, variable names normally refer to
Xlocal variables, which are created automatically when referenced and
Xdeleted when the procedure returns.  One local variable is automatically
Xcreated for each of the procedure's arguments.
XGlobal variables can only be accessed by invoking
Xthe \fBglobal\fR command.
X.IP
XThe \fBproc\fR command returns the null string.  When a procedure is
Xinvoked, the procedure's return value is the value specified in a
X\fBreturn\fR command.  If the procedure doesn't execute an explicit
X\fBreturn\fR, then its return value is the value of the last command
Xexecuted in the procedure's body.
XIf an error occurs while executing the procedure
Xbody, then the procedure-as-a-whole will return that same error.
X.TP
X\fBputs \fIfileId string \fR?\fBnonewline\fR?
X.VS
XWrites the characters given by \fIstring\fR to the file given
Xby \fIfileId\fR.
X\fBPuts\fR normally outputs a newline character after \fIstring\fR,
Xbut this feature may be suppressed by specifying the \fBnonewline\fR
Xargument.
XOutput to files is buffered internally by Tcl; the \fBflush\fR
Xcommand may be used to force buffered characters to be output.
X\fIFileId\fR must have been the return
Xvalue from a previous call to \fBopen\fR, or it may be
X\fBstdout\fR or \fBstderr\fR to refer to one of the standard I/O
Xchannels; it must refer to a file that was opened for
Xwriting.
X.TP
X\fBpwd\fR
X.br
XReturns the path name of the current working directory.
X.TP
X\fBread \fIfileId\fR
X.TP
X\fBread \fIfileId \fBnonewline\fR
X.TP
X\fBread \fIfileId numBytes\fR
XIn the first form, all of the remaining bytes are read from the file
Xgiven by \fIfileId\fR; they are returned as the result of the command.
XIf \fBnonewline\fR is specified as an additional argument, then the last
Xcharacter of the file is discarded if it is a newline.
XIn the third form, the extra argument specifies how many bytes to read;
Xexactly this many bytes will be read and returned, unless there are fewer than
X\fInumBytes\fR bytes left in the file; in this case, all the remaining
Xbytes are returned.
X\fIFileId\fR must be \fBstdin\fR or the return
Xvalue from a previous call to \fBopen\fR; it must
Xrefer to a file that was opened for reading.
X.TP
X\fBregexp \fR?\fB\-indices\fR? \fR?\fB\-nocase\fR? \fIexp string \fR?\fImatchVar\fR? ?\fIsubMatchVar subMatchVar ...\fR?
XDetermines whether the regular expression \fIexp\fR matches part or
Xall of \fIstring\fR and returns 1 if it does, 0 if it doesn't.
XSee REGULAR EXPRESSIONS above for complete information on the
Xsyntax of \fIexp\fR and how it is matched against \fIstring\fR.
X.RS
X.LP
XIf the \fB\-nocase\fR switch is specified then upper-case
Xcharacters in \fIstring\fR
Xare treated as lower case during the matching process.
XThe \fB\-nocase\fR switch must be specified before \fIexp\fR and
Xmay not be abbreviated.
X.LP
XIf additional arguments are specified after \fIstring\fR then they
Xare treated as the names of variables to use to return
Xinformation about which part(s) of \fIstring\fR matched \fIexp\fR.
X\fIMatchVar\fR will be set to the range of \fIstring\fR that
Xmatched all of \fIexp\fR.  The first \fIsubMatchVar\fR will contain
Xthe characters in \fIstring\fR that matched the leftmost parenthesized
Xsubexpression within \fIexp\fR, the next \fIsubMatchVar\fR will
Xcontain the characters that matched the next parenthesized
Xsubexpression to the right in \fIexp\fR, and so on.
X.LP
XNormally, \fImatchVar\fR and the \fIsubMatchVar\fRs are set to hold
Xthe matching characters from \fBstring\fR.
XHowever, if the \fB\-indices\fR switch is specified then each variable
Xwill contain a list of two decimal strings giving the indices
Xin \fIstring\fR of the first and last characters in the matching
Xrange of characters.
XThe \fB\-indices\fR switch must be specified before the \fIexp\fR
Xargument and may not be abbreviated.
X.LP
XIf there are more more \fIsubMatchVar\fR's than parenthesized
Xsubexpressions within \fIexp\fR, or if a particular subexpression
Xin \fIexp\fR doesn't match the string (e.g. because it was in a
Xportion of the expression that wasn't matched), then the corresponding
X\fIsubMatchVar\fR will be set to ``\fB\-1 \-1\fR'' if \fB\-indices\fR
Xhas been specified or to an empty string otherwise.
X.RE
X.TP
X\fBregsub \fR?\fB\-all\fR? ?\fB\-nocase\fR? \fIexp string subSpec varName\fR
XThis command matches the regular expression \fIexp\fR against
X\fIstring\fR using the rules described in REGULAR EXPRESSIONS
Xabove.
XIf there is no match, then the command returns 0 and does nothing
Xelse.
XIf there is a match, then the command returns 1 and also copies
X\fIstring\fR to the variable whose name is given by \fIvarName\fR.
XWhen copying \fIstring\fR, the portion of \fIstring\fR that
Xmatched \fIexp\fR is replaced with \fIsubSpec\fR.
XIf \fIsubSpec\fR contains a ``&'' or ``\e0'', then it is replaced
Xin the substitution with the portion of \fIstring\fR that
Xmatched \fIexp\fR.
XIf \fIsubSpec\fR contains a ``\e\fIn\fR'', where \fIn\fR is a digit
Xbetween 1 and 9, then it is replaced in the substitution with
Xthe portion of \fIstring\fR that matched the \fIn\fR-th
Xparenthesized subexpression of \fIexp\fR.
XAdditional backslashes may be used in \fIsubSpec\fR to prevent special
Xinterpretation of ``&'' or ``\e0'' or ``\e\fIn\fR'' or
Xbackslash.
XThe use of backslashes in \fIsubSpec\fR tends to interact badly
Xwith the Tcl parser's use of backslashes, so it's generally
Xsafest to enclose \fIsubSpec\fR in braces if it includes
Xbackslashes.
XIf the \fB\-all\fR argument is specified, then all ranges in
X\fIstring\fR that match \fIexp\fR are found and substitution is
Xperformed for each of these ranges;  otherwise only the first
Xmatching range is found and substituted.
XIf \fB\-all\fR is specified, then ``&'' and ``\e\fIn\fR''
Xsequences are handled for each substitution using the information
Xfrom the corresponding match.
XIf the \fB\-nocase\fR argument is specified, then upper-case
Xcharacters in \fIstring\fR are converted to lower-case before
Xmatching against \fIexp\fR;  however, substitutions specified
Xby \fIsubSpec\fR use the original unconverted form of \fIstring\fR.
XThe \fB\-all\fR and \fB\-nocase\fR arguments must be specified
Xexactly:  no abbreviations are permitted.
X.VE
X.TP
X\fBrename \fIoldName newName\fR
XRename the command that used to be called \fIoldName\fR so that it
Xis now called \fInewName\fR.  If \fInewName\fR is an empty string
X(e.g. {}) then \fIoldName\fR is deleted.  The \fBrename\fR command
Xreturns an empty string as result.
X.TP
X\fBreturn \fR?\fIvalue\fR?
XReturn immediately from the current procedure
X(or top-level command or \fBsource\fR command),
Xwith \fIvalue\fR as the return value.  If \fIvalue\fR is not specified,
Xan empty string will be returned as result.
X.TP
X\fBscan \fIstring format varname1 \fR?\fIvarname2 ...\fR?
XThis command parses fields from an input string in the same fashion
Xas the C \fBsscanf\fR procedure.  \fIString\fR gives the input to
Xbe parsed and \fIformat\fR indicates how to parse it, using \fB%\fR
Xfields as in \fBsscanf\fR.  All of the \fBsscanf\fR options are valid;
Xsee the \fBsscanf\fR man page for details.  Each \fIvarname\fR gives
Xthe name of a variable; when a field is scanned from \fIstring\fR,
Xthe result is converted back into a string and assigned to the
Xcorresponding \fIvarname\fR.  The only unusual conversion is for
X\fB%c\fR.  For \fB%c\fR conversions a single character value is
Xconverted to a decimal string, which is then assigned to the
Xcorresponding \fIvarname\fR;
X.VS
Xno field width may be specified for this conversion.
X.TP
X\fBseek \fIfileId offset \fR?\fIorigin\fR?
XChange the current access position for \fIfileId\fR.
XThe \fIoffset\fR and \fIorigin\fR arguments specify the position at
Xwhich the next read or write will occur for \fIfileId\fR.
X\fIOffset\fR must be a number (which may be negative) and \fIorigin\fR
Xmust be one of the following:
X.RS
X.TP
X\fBstart\fR
XThe new access position will be \fIorigin\fR bytes from the start
Xof the file.
X.TP
X\fBcurrent\fR
XThe new access position will be \fIorigin\fR bytes from the current
Xaccess position; a negative \fIorigin\fR moves the access position
Xbackwards in the file.
X.TP
X\fBend\fR
XThe new access position will be \fIorigin\fR bytes from the end of
Xthe file.  A negative \fIorigin\fR places the access position before
Xthe end-of-file, and a positive \fIorigin\fR places the access position
Xafter the end-of-file.
X.LP
XThe \fIorigin\fR argument defaults to \fBstart\fR.
X\fIFileId\fR must have been the return
Xvalue from a previous call to \fBopen\fR, or it may be \fBstdin\fR,
X\fBstdout\fR, or \fBstderr\fR to refer to one of the standard I/O
Xchannels.
XThis command returns an empty string.
X.RE
X.VE
X.TP
X\fBset \fIvarname \fR?\fIvalue\fR?
XReturns the value of variable \fIvarname\fR.
XIf \fIvalue\fR is specified, then set
Xthe value of \fIvarname\fR to \fIvalue\fR, creating a new variable
Xif one doesn't already exist, and return its value.
X.VS
XIf \fIvarName\fR contains an open parenthesis and ends with a
Xclose parenthesis, then it refers to an array element:  the characters
Xbefore the open parenthesis are the name of the array, and the characters
Xbetween the parentheses are the index within the array.
XOtherwise \fIvarName\fR refers to a scalar variable.
X.VE
XIf no procedure is active, then \fIvarname\fR refers to a global
Xvariable.
XIf a procedure is active, then \fIvarname\fR refers to a parameter
Xor local variable of the procedure, unless the \fIglobal\fR command
Xhas been invoked to declare \fIvarname\fR to be global.
X.TP
X\fBsource \fIfileName\fR
XRead file \fIfileName\fR and pass the contents to the Tcl interpreter
Xas a sequence of commands to execute in the normal fashion.  The return
Xvalue of \fBsource\fR is the return value of the last command executed
Xfrom the file.  If an error occurs in executing the contents of the
Xfile, then the \fBsource\fR command will return that error.
XIf a \fBreturn\fR command is invoked from within the file, the remainder of
Xthe file will be skipped and the \fBsource\fR command will return
Xnormally with the result from the \fBreturn\fR command.
XIf \fIfileName\fR starts with a tilde, then it is tilde-substituted
Xas described in the \fBTcl_TildeSubst\fR manual entry.
X.TP
X\fBsplit \fIstring \fR?\fIsplitChars\fR?
XReturns a list created by splitting \fIstring\fR at each character
Xthat is in the \fIsplitChars\fR argument.
XEach element of the result list will consist of the
Xcharacters from \fIstring\fR between instances of the
Xcharacters in \fIsplitChars\fR.
XEmpty list elements will be generated if \fIstring\fR contains
Xadjacent characters in \fIsplitChars\fR, or if the first or last
Xcharacter of \fIstring\fR is in \fIsplitChars\fR.
XIf \fIsplitChars\fR is an empty string then each character of
X\fIstring\fR becomes a separate element of the result list.
X\fISplitChars\fR defaults to the standard white-space characters.
XFor example,
X.RS
X.DS
X\fBsplit "comp.unix.misc" .\fR
X.DE
Xreturns \fB"comp unix misc"\fR and
X.DS
X\fBsplit "Hello world" {}\fR
X.DE
Xreturns \fB"H e l l o { } w o r l d"\fR.
X.VE
X.RE
X.TP
X\fBstring \fIoption arg \fR?\fIarg ...?\fR
XPerform one of several string operations, depending on \fIoption\fR.
XThe legal \fIoption\fRs (which may be abbreviated) are:
X.RS
X.TP
X\fBstring compare \fIstring1 string2\fR
XPerform a character-by-character comparison of strings \fIstring1\fR and
X\fIstring2\fR in the same way as the C \fBstrcmp\fR procedure.  Return
X-1, 0, or 1, depending on whether \fIstring1\fR is lexicographically
Xless than, equal to, or greater than \fIstring2\fR.
X.TP
X\fBstring first \fIstring1 string2\fR
XSearch \fIstring2\fR for a sequence of characters that exactly match
Xthe characters in \fIstring1\fR.  If found, return the index of the
Xfirst character in the first such match within \fIstring2\fR.  If not
Xfound, return -1.
X.br
X.VS
X.TP
X\fBstring index \fIstring charIndex\fR
XReturns the \fIcharIndex\fR'th character of the \fIstring\fR
Xargument.  A \fIcharIndex\fR of 0 corresponds to the first
Xcharacter of the string.
XIf \fIcharIndex\fR is less than 0 or greater than
Xor equal to the length of the string then an empty string is
Xreturned.
X.VE
X.TP
X\fBstring last \fIstring1 string2\fR
XSearch \fIstring2\fR for a sequence of characters that exactly match
Xthe characters in \fIstring1\fR.  If found, return the index of the
Xfirst character in the last such match within \fIstring2\fR.  If there
Xis no match, then return \-1.
X.br
X.VS
X.TP
X\fBstring length \fIstring\fR
XReturns a decimal string giving the number of characters in \fIstring\fR.
X.VE
X.TP
X\fBstring match \fIpattern\fR \fIstring\fR
XSee if \fIpattern\fR matches \fIstring\fR; return 1 if it does, 0
Xif it doesn't.  Matching is done in a fashion similar to that
Xused by the C-shell.  For the two strings to match, their contents
Xmust be identical except that the following special sequences
Xmay appear in \fIpattern\fR:
X.RS
X.IP \fB*\fR 10
XMatches any sequence of characters in \fIstring\fR,
Xincluding a null string.
X.IP \fB?\fR 10
XMatches any single character in \fIstring\fR.
X.IP \fB[\fIchars\fB]\fR 10
XMatches any character in the set given by \fIchars\fR.  If a sequence
Xof the form
X\fIx\fB\-\fIy\fR appears in \fIchars\fR, then any character
Xbetween \fIx\fR and \fIy\fR, inclusive, will match.
X.IP \fB\e\fIx\fR 10
XMatches the single character \fIx\fR.  This provides a way of
Xavoiding the special interpretation of the characters
X\fB*?[]\e\fR in \fIpattern\fR.
X.RE
X.br
X.VS
X.TP
X\fBstring range \fIstring first last\fR
XReturns a range of consecutive characters from \fIstring\fR, starting
Xwith the character whose index is \fIfirst\fR and ending with the
Xcharacter whose index is \fIlast\fR.  An index of 0 refers to the
Xfirst character of the string.  \fILast\fR may be \fBend\fR (or any
Xabbreviation of it) to refer to the last character of the string.
XIf \fIfirst\fR is less than zero then it is treated as if it were zero, and
Xif \fIlast\fR is greater than or equal to the length of the string then
Xit is treated as if it were \fBend\fR.  If \fIfirst\fR is greater than
X\fIlast\fR then an empty string is returned.
X.TP
X\fBstring tolower \fIstring\fR
XReturns a value equal to \fIstring\fR except that all upper case
Xletters have been converted to lower case.
X.TP
X\fBstring toupper \fIstring\fR
XReturns a value equal to \fIstring\fR except that all lower case
Xletters have been converted to upper case.
X.TP
X\fBstring trim \fIstring\fR ?\fIchars\fR?
XReturns a value equal to \fIstring\fR except that any leading
Xor trailing characters from the set given by \fIchars\fR are
Xremoved.
XIf \fIchars\fR is not specified then white space is removed
X(spaces, tabs, newlines, and carriage returns).
X.TP
X\fBstring trimleft \fIstring\fR ?\fIchars\fR?
XReturns a value equal to \fIstring\fR except that any
Xleading characters from the set given by \fIchars\fR are
Xremoved.
XIf \fIchars\fR is not specified then white space is removed
X(spaces, tabs, newlines, and carriage returns).
X.TP
X\fBstring trimright \fIstring\fR ?\fIchars\fR?
XReturns a value equal to \fIstring\fR except that any
Xtrailing characters from the set given by \fIchars\fR are
Xremoved.
XIf \fIchars\fR is not specified then white space is removed
X(spaces, tabs, newlines, and carriage returns).
X.RE
X.TP
X\fBtell \fIfileId\fR
XReturns a decimal string giving the current access position in
X\fIfileId\fR.
X\fIFileId\fR must have been the return
Xvalue from a previous call to \fBopen\fR, or it may be \fBstdin\fR,
X\fBstdout\fR, or \fBstderr\fR to refer to one of the standard I/O
Xchannels.
X.VE
X.TP
X\fBtime \fIcommand\fR ?\fIcount\fR?
XThis command will call the Tcl interpreter \fIcount\fR
Xtimes to execute \fIcommand\fR (or once if \fIcount\fR isn't
Xspecified).  It will then return a string of the form
X.RS
X.DS
X\fB503 microseconds per iteration\fR
X.DE
Xwhich indicates the average amount of time required per iteration,
Xin microseconds.
XTime is measured in elapsed time, not CPU time.
X.RE
X.TP
X\fBtrace \fIoption\fR ?\fIarg arg ...\fR?
X.VS
XCause Tcl commands to be executed whenever certain operations are
Xinvoked.  At present, only variable tracing is implemented. The
Xlegal \fIoption\fR's (which may be abbreviated) are:
X.RS
X.TP
X\fBtrace variable \fIname ops command\fR
XArrange for \fIcommand\fR to be executed whenever variable \fIname\fR
Xis accessed in one of the ways given by \fIops\fR.  \fIName\fR may
Xrefer to a normal variable, an element of an array, or to an array
Xas a whole (i.e. \fIname\fR may be just the name of an array, with no
Xparenthesized index).  If \fIname\fR refers to a whole array, then
X\fIcommand\fR is invoked whenever any element of the array is
Xmanipulated.
X.RS
X.LP
X\fIOps\fR indicates which operations are of interest, and consists of
Xone or more of the following letters:
X.RS
X.TP
X\fBr\fR
XInvoke \fIcommand\fR whenever the variable is read.
X.TP
X\fBw\fR
XInvoke \fIcommand\fR whenever the variable is written.
X.TP
X\fBu\fR
XInvoke \fIcommand\fR whenever the variable is unset.  Variables
Xcan be unset explicitly with the \fBunset\fR command, or
Ximplicitly when procedures return (all of their local variables
Xare unset).  Variables are also unset when interpreters are
Xdeleted, but traces will not be invoked because there is no
Xinterpreter in which to execute them.
X.RE
X.LP
XWhen the trace triggers, three arguments are appended to
X\fIcommand\fR so that the actual command is as follows:
X.DS C
X\fIcommand name1 name2 op\fR
X.DE
X\fIName1\fR and \fIname2\fR give the name(s) for the variable
Xbeing accessed:  if the variable is a scalar then \fIname1\fR
Xgives the variable's name and \fIname2\fR is an empty string;
Xif the variable is an array element then \fIname1\fR gives the
Xname of the array and name2 gives the index into the array;
Xif an entire array is being deleted and the trace was registered
Xon the overall array, rather than a single element, then \fIname1\fR
Xgives the array name and \fIname2\fR is an empty string.
X\fIOp\fR indicates what operation is being performed on the
Xvariable, and is one of \fBr\fR, \fBw\fR, or \fBu\fR as
Xdefined above.
X.LP
X\fICommand\fR executes in the same context as the code that invoked
Xthe traced operation:  if the variable was accessed as part of a
XTcl procedure, then \fIcommand\fR will have access to the same
Xlocal variables as code in the procedure.  This context may be
Xdifferent than the context in which the trace was created.
XNote that \fIname1\fR may not necessarily be the same as the name
Xused to set the trace on the variable;  differences can occur if
Xthe access is made through a variable defined with the \fBupvar\fR
Xcommand.
X.LP
XFor read and write traces, \fIcommand\fR can modify
Xthe variable to affect the result of the traced operation.
XIf \fIcommand\fR modifies the value of a variable during a
Xread trace, then the value returned by the traced read operation
Xwill be the value of the variable after \fIcommand\fR completes.
XFor write traces, \fIcommand\fR is invoked after the variable's
Xvalue has been changed; it can write a new value into the variable
Xto override the original value specified in the write operation.
XThe value returned by the traced write operation will be the
Xvalue of the variable when \fIcommand\fR completes.
XIf \fIcommand\fR returns an error during a read or write trace,
Xthen the traced operation is aborted with an error.
XThis mechanism can be used to implement read-only variables,
Xfor example.
X\fICommand\fR's result is always ignored.
X.LP
XWhile \fIcommand\fR is executing during a read or write trace, traces
Xon the variable are temporarily disabled.
XThis means that reads and writes invoked by
X\fIcommand\fR will occur directly, without invoking \fIcommand\fR
X(or any other traces) again.
XIt is illegal to \fBunset\fR a variable while a trace
Xis active for it.
XIt is also illegal to \fBunset\fR an array if there are
Xtraces active for any of the array's elements.
X.LP
XWhen an unset trace is invoked, the variable has already been
Xdeleted:  it will appear to be undefined with no traces.
XIf an unset occurs because of a procedure return, then the
Xtrace will be invoked in the variable context of the procedure
Xbeing returned to:  the stack frame of the returning procedure
Xwill no longer exist.
XTraces are not disabled during unset traces, so if an unset trace
Xcommand creates a new trace and accesses the variable, the
Xtrace will be invoked.
X.LP
XIf there are multiple traces on a variable they are invoked
Xin order of creation, most-recent first.
XIf one trace returns an error, then no further traces are
Xinvoked for the variable.
XIf an array element has a trace set, and there is also a trace
Xset on the array as a whole, the trace on the overall array
Xis invoked before the one on the element.
X.LP
XOnce created, the trace remains in effect either until the
Xtrace is removed with the \fBtrace vdelete\fR command described
Xbelow, until the variable is unset, or until the interpreter
Xis deleted.
XUnsetting an element of array will remove any traces on that
Xelement, but will not remove traces on the overall array.
X.LP
XThis command returns an empty string.
X.RE
X.TP
X\fBtrace vdelete \fIname ops command\fR
XIf there is a trace set on variable \fIname\fR with the
Xoperations and command given by \fIops\fR and \fIcommand\fR,
Xthen the trace is removed, so that \fIcommand\fR will never
Xagain be invoked.
XReturns an empty string.
X.TP
X\fBtrace vinfo \fIname\fR
XReturns a list containing one element for each trace
Xcurrently set on variable \fIname\fR.
XEach element of the list is itself a list containing two
Xelements, which are the \fIops\fR and \fIcommand\fR associated
Xwith the trace.
XIf \fIname\fR doesn't exist or doesn't have any traces set, then
Xthe result of the command will be an empty string.
X.RE
X.TP
X\fBunknown \fIcmdName \fR?\fIarg arg ...\fR?
XThis command doesn't actually exist as part of Tcl, but Tcl will
Xinvoke it if it does exist.
XIf the Tcl interpreter encounters a command name for which there
Xis not a defined command, then Tcl checks for the existence of
Xa command named \fBunknown\fR.
XIf there is no such command, then the interpeter returns an
Xerror.
XIf the \fBunknown\fR command exists, then it is invoked with
Xarguments consisting of the fully-substituted name and arguments
Xfor the original non-existent command.
XThe \fBunknown\fR command typically does things like searching
Xthrough library directories for a command procedure with the name
X\fIcmdName\fR, or expanding abbreviated command names to full-length,
Xor automatically executing unknown commands as UNIX sub-processes.
XIn some cases (such as expanding abbreviations) \fBunknown\fR will
Xchange the original command slightly and then (re-)execute it.
XThe result of the \fBunknown\fR command is used as the result for
Xthe original non-existent command.
X.TP
X\fBunset \fIname \fR?\fIname name ...\fR?
XRemove one or more variables.
XEach \fIname\fR is a variable name, specified in any of the
Xways acceptable to the \fBset\fR command.
XIf a \fIname\fR refers to an element of an array, then that
Xelement is removed without affecting the rest of the array.
XIf a \fIname\fR consists of an array name with no parenthesized
Xindex, then the entire array is deleted.
XThe \fBunset\fR command returns an empty string as result.
XAn error occurs if any of the variables doesn't exist, or if
Xany of the variables has an active trace.
X.VE
X.TP
X\fBuplevel \fR?\fIlevel\fR?\fI command \fR?\fIcommand ...\fR?
XAll of the \fIcommand\fR arguments are concatenated as if they had
Xbeen passed to \fBconcat\fR; the result is then evaluated in the
Xvariable context indicated by \fIlevel\fR.  \fBUplevel\fR returns
Xthe result of that evaluation.  If \fIlevel\fR is an integer, then
Xit gives a distance (up the procedure calling stack) to move before
Xexecuting the command.  If \fIlevel\fR consists of \fB#\fR followed by
Xa number then the number gives an absolute level number.  If \fIlevel\fR
Xis omitted then it defaults to \fB1\fR.  \fILevel\fR cannot be
Xdefaulted if the first \fIcommand\fR argument starts with a digit or \fB#\fR.
XFor example, suppose that procedure \fBa\fR was invoked
Xfrom top-level, and that it called \fBb\fR, and that \fBb\fR called \fBc\fR.
XSuppose that \fBc\fR invokes the \fBuplevel\fR command.  If \fIlevel\fR
Xis \fB1\fR or \fB#2\fR  or omitted, then the command will be executed
Xin the variable context of \fBb\fR.  If \fIlevel\fR is \fB2\fR or \fB#1\fR
Xthen the command will be executed in the variable context of \fBa\fR.
XIf \fIlevel\fR is \fB3\fR or \fB#0\fR then the command will be executed
Xat top-level (only global variables will be visible).
XThe \fBuplevel\fR command causes the invoking procedure to disappear
Xfrom the procedure calling stack while the command is being executed.
XIn the above example, suppose \fBc\fR invokes the command
X.RS
X.DS
X\fBuplevel 1 {set x 43; d}
X.DE
Xwhere \fBd\fR is another Tcl procedure.  The \fBset\fR command will
Xmodify the variable \fBx\fR in \fBb\fR's context, and \fBd\fR will execute
Xat level 3, as if called from \fBb\fR.  If it in turn executes
Xthe command
X.DS
X\fBuplevel {set x 42}
X.DE
Xthen the \fBset\fR command will modify the same variable \fBx\fR in \fBb\fR's
Xcontext:  the procedure \fBc\fR does not appear to be on the call stack
Xwhen \fBd\fR is executing.  The command ``\fBinfo level\fR'' may
Xbe used to obtain the level of the current procedure.
X\fBUplevel\fR makes it possible to implement new control
Xconstructs as Tcl procedures (for example, \fBuplevel\fR could
Xbe used to implement the \fBwhile\fR construct as a Tcl procedure).
X.RE
X.TP
X\fBupvar \fR?\fIlevel\fR? \fIotherVar myVar \fR?\fIotherVar myVar \fR...?
X.VS
XThis command arranges for one or more local variables in the current
Xprocedure to refer to variables in an enclosing procedure call or
Xto global variables.
X\fILevel\fR may have any of the forms permitted for the \fBuplevel\fR
Xcommand, and may be omitted if the first letter of the first \fIotherVar\fR
Xisn't \fB#\fR or a digit (it defaults to \fB1\fR).
XFor each \fIotherVar\fR argument, \fBupvar\fR makes the variable
Xby that name in the procedure frame given by \fIlevel\fR (or at
Xglobal level, if \fIlevel\fR is \fB#0\fR) accessible
Xin the current procedure by the name given in the corresponding
X\fImyVar\fR argument.
XThe variable named by \fIotherVar\fR need not exist at the time of the
Xcall;  it will be created the first time \fImyVar\fR is referenced, just like
Xan ordinary variable.
X\fBUpvar\fR may only be invoked from within procedures.
XNeither \fIotherVar\fR or \fImyVar\fR may refer to an element of an
Xarray.
X\fBUpvar\fR returns an empty string.
X.RS
X.LP
XThe \fBupvar\fR command simplifies the implementation of call-by-name
Xprocedure calling and also makes it easier to build new control constructs
Xas Tcl procedures.
XFor example, consider the following procedure:
X.DS
X.ta 1c 2c 3c
X\fBproc add2 name {
X    upvar $name x
X    set x [expr $x+2]
X}
X.DE
X\fBAdd2\fR is invoked with an argument giving the name of a variable,
Xand it adds two to the value of that variable.
XAlthough \fBadd2\fR could have been implemented using \fBuplevel\fR
Xinstead of \fBupvar\fR, \fBupvar\fR makes it simpler for \fBadd2\fR
Xto access the variable in the caller's procedure frame.
X.VE
X.RE
X.TP
X\fBwhile \fItest body
X.VS
XThe \fIwhile\fR command evaluates \fItest\fR as an expression
X(in the same way that \fBexpr\fR evaluates its argument).
XThe value of the expression must be numeric; if it is non-zero
Xthen \fIbody\fR is executed by passing it to the Tcl interpreter.
XOnce \fIbody\fR has been executed then \fItest\fR is evaluated
Xagain, and the process repeats until eventually \fItest\fR
Xevaluates to a zero numeric value.  \fBContinue\fR
Xcommands may be executed inside \fIbody\fR to terminate the current
Xiteration of the loop, and \fBbreak\fR
Xcommands may be executed inside \fIbody\fR to cause immediate
Xtermination of the \fBwhile\fR command.  The \fBwhile\fR command
Xalways returns an empty string.
X.VE
X
X.SH "BUILT-IN VARIABLES"
X.PP
XThe following global variables are created and managed automatically
Xby the Tcl library.  Except where noted below, these variables should
Xnormally be treated as read-only by application-specific code and by users.
X.TP
X\fBenv\fR
X.br
X.VS
XThis variable is maintained by Tcl as an array
Xwhose elements are the environment variables for the process.
XReading an element will return the value of the corresponding
Xenvironment variable.
XSetting an element of the array will modify the corresponding
Xenvironment variable or create a new one if it doesn't already
Xexist.
XUnsetting an element of \fBenv\fR will remove the corresponding
Xenvironment variable.
XChanges to the \fBenv\fR array will affect the environment
Xpassed to children by commands like \fBexec\fR.
XIf the entire \fBenv\fR array is unset then Tcl will stop
Xmonitoring \fBenv\fR accesses and will not update environment
Xvariables.
X.TP
X\fBerrorCode\fR
XAfter an error has occurred, this variable will be set to hold
Xadditional information about the error in a form that is easy
Xto process with programs.
X\fBerrorCode\fR consists of a Tcl list with one or more elements.
XThe first element of the list identifies a general class of
Xerrors, and determines the format of the rest of the list.
XThe following formats for \fBerrorCode\fR are used by the
XTcl core; individual applications may define additional formats.
X.RS
X.TP
X\fBCHILDKILLED\fI pid sigName msg\fR
XThis format is used when a child process has been killed because of
Xa signal.  The second element of \fBerrorCode\fR will be the
Xprocess's identifier (in decimal).
XThe third element will be the symbolic name of the signal that caused
Xthe process to terminate; it will be one of the names from the
Xinclude file signal.h, such as \fBSIGPIPE\fR.
XThe fourth element will be a short human-readable message
Xdescribing the signal, such as ``write on pipe with no readers''
Xfor \fBSIGPIPE\fR.
X.TP
X\fBCHILDSTATUS\fI pid code\fR
XThis format is used when a child process has exited with a non-zero
Xexit status.  The second element of \fBerrorCode\fR will be the
Xprocess's identifier (in decimal) and the third element will be the exit
Xcode returned by the process (also in decimal).
X.TP
X\fBCHILDSUSP\fI pid code\fR
XThis format is used when a child process has been suspended because
Xof a signal.
XThe second element of \fBerrorCode\fR will be the process's identifier,
Xin decimal.
XThe third element will be the symbolic name of the signal that caused
Xthe process to suspend; this will be one of the names from the
Xinclude file signal.h, such as \fBSIGTTIN\fR.
XThe fourth element will be a short human-readable message
Xdescribing the signal, such as ``background tty read''
Xfor \fBSIGTTIN\fR.
X.TP
X\fBNONE\fR
X.br
XThis format is used for errors where no additional information is
Xavailable for an error besides the message returned with the
Xerror.  In these cases \fBerrorCode\fR will consist of a list
Xcontaining a single element whose contents are \fBNONE\fR.
X.TP
X\fBUNIX \fIerrName msg\fR
XIf the first element of \fBerrorCode\fR is \fBUNIX\fR, then
Xthe error occurred during a UNIX kernel call.
XThe second element of the list will contain the symbolic name
Xof the error that occurred, such as \fBENOENT\fR; this will
Xbe one of the values defined in the include file errno.h.
XThe third element of the list will be a human-readable
Xmessage corresponding to \fIerrName\fR, such as
X``no such file or directory'' for the \fBENOENT\fR case.
X.PP
XTo set \fBerrorCode\fR, applications should use library
Xprocedures such as \fBTcl_SetErrorCode\fR and
X\fBTcl_UnixError\fR, or they may invoke the \fBerror\fR command.
XIf one of these methods hasn't been used, then the Tcl
Xinterpreter will reset the variable to \fBNONE\fR after
Xthe next error.
X.RE
X.VE
X.TP
X\fBerrorInfo\fR
XAfter an error has occurred, this string will contain one or more lines
Xidentifying the Tcl commands and procedures that were being executed
Xwhen the most recent error occurred.
XIts contents take the form of a stack trace showing the various
Xnested Tcl commands that had been invoked at the time of the error.
X
X.SH AUTHOR
XJohn Ousterhout, University of California at Berkeley ([e-mail])
X.sp
XMany people have contributed to Tcl in various ways, but the following
Xpeople have made unusually large contributions:
X.sp
X.nf
XBill Carpenter
XPeter Da Silva
XMark Diekhans
XKarl Lehenbauer
XMary Ann May-Pumphrey
END_OF_FILE
if test 41512 -ne `wc -c <'tcl6.1/doc/Tcl.man.3'`; then
    echo shar: \"'tcl6.1/doc/Tcl.man.3'\" unpacked with wrong size!
fi
# end of 'tcl6.1/doc/Tcl.man.3'
fi
echo shar: End of archive 32 \(of 33\).
cp /dev/null ark32isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 33 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0

exit 0 # Just in case...
--
Kent Landfield                   INTERNET: [e-mail]
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    [phone]         FAX:      [phone]
Please send comp.sources.misc-related mail to [e-mail].